home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 January: Mac OS SDK / Dev.CD Jan 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / PInterfaces / CodeFragments.p < prev    next >
Encoding:
Text File  |  1998-08-17  |  15.1 KB  |  530 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        CodeFragments.p
  3.  
  4.      Contains:    Public Code Fragment Manager Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 8.1
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1992-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. }
  17. {
  18.    •
  19.    ===========================================================================================
  20.    The Code Fragment Manager API
  21.    =============================
  22. }
  23.  
  24.  
  25. {$IFC UNDEFINED UsingIncludes}
  26. {$SETC UsingIncludes := 0}
  27. {$ENDC}
  28.  
  29. {$IFC NOT UsingIncludes}
  30.  UNIT CodeFragments;
  31.  INTERFACE
  32. {$ENDC}
  33.  
  34. {$IFC UNDEFINED __CODEFRAGMENTS__}
  35. {$SETC __CODEFRAGMENTS__ := 1}
  36.  
  37. {$I+}
  38. {$SETC CodeFragmentsIncludes := UsingIncludes}
  39. {$SETC UsingIncludes := 1}
  40.  
  41. {$IFC UNDEFINED __MACTYPES__}
  42. {$I MacTypes.p}
  43. {$ENDC}
  44. {$IFC UNDEFINED __FILES__}
  45. {$I Files.p}
  46. {$ENDC}
  47.  
  48.  
  49. {$PUSH}
  50. {$ALIGN MAC68K}
  51. {$LibExport+}
  52.  
  53. {
  54.    §
  55.    ===========================================================================================
  56.    General Types and Constants
  57.    ===========================
  58. }
  59.  
  60.  
  61.  
  62. CONST
  63.     kCFragResourceType            = 'cfrg';
  64.     kCFragResourceID            = 0;
  65.     kCFragLibraryFileType        = 'shlb';
  66.     kCFragAllFileTypes            = $FFFFFFFF;
  67.  
  68.  
  69.  
  70. TYPE
  71.     CFragArchitecture                    = OSType;
  72.  
  73. CONST
  74.     kPowerPCCFragArch            = 'pwpc';
  75.     kMotorola68KCFragArch        = 'm68k';
  76.     kAnyCFragArch                = $3F3F3F3F;
  77.  
  78. {$IFC TARGET_CPU_PPC }
  79.     kCompiledCFragArch            = 'pwpc';
  80.  
  81. {$ENDC}  {TARGET_CPU_PPC}
  82.  
  83. {$IFC TARGET_CPU_68K }
  84.     kCompiledCFragArch            = 'm68k';
  85.  
  86. {$ENDC}  {TARGET_CPU_68K}
  87.  
  88.  
  89. TYPE
  90.     CFragVersionNumber                    = UInt32;
  91.  
  92. CONST
  93.     kNullCFragVersion            = 0;
  94.     kWildcardCFragVersion        = $FFFFFFFF;
  95.  
  96.  
  97.  
  98. TYPE
  99.     CFragUsage                            = UInt8;
  100.  
  101. CONST
  102.     kImportLibraryCFrag            = 0;                            {  Standard CFM import library. }
  103.     kApplicationCFrag            = 1;                            {  MacOS application. }
  104.     kDropInAdditionCFrag        = 2;                            {  Application or library private extension/plug-in }
  105.     kStubLibraryCFrag            = 3;                            {  Import library used for linking only }
  106.     kWeakStubLibraryCFrag        = 4;                            {  Import library used for linking only and will be automatically weak linked }
  107.  
  108.  
  109.     kIsCompleteCFrag            = 0;                            {  A "base" fragment, not an update. }
  110.     kFirstCFragUpdate            = 1;                            {  The first update, others are numbered 2, 3, ... }
  111.  
  112.  
  113.     kCFragGoesToEOF                = 0;
  114.  
  115.  
  116.  
  117.  
  118.  
  119. TYPE
  120.     CFragLocatorKind                    = UInt8;
  121.  
  122. CONST
  123.     kMemoryCFragLocator            = 0;                            {  Container is already addressable. }
  124.     kDataForkCFragLocator        = 1;                            {  Container is in a file's data fork. }
  125.     kResourceCFragLocator        = 2;                            {  Container is in a file's resource fork. }
  126.     kByteStreamCFragLocator        = 3;                            {  ! Reserved for possible future use! }
  127.     kNamedFragmentCFragLocator    = 4;                            {  ! Reserved for possible future use! }
  128.  
  129.  
  130. {
  131.    --------------------------------------------------------------------------------------
  132.    A 'cfrg' resource consists of a header followed by a sequence of variable length
  133.    members.  The constant kDefaultCFragNameLen only provides for a legal ANSI declaration
  134.    and for a reasonable display in a debugger.  The actual name field is cut to fit.
  135.    There may be "extensions" after the name, the memberSize field includes them.  The
  136.    general form of an extension is a 16 bit type code followed by a 16 bit size in bytes.
  137.    Only one standard extension type is defined at present, it is used by SOM's searching
  138.    mechanism.
  139. }
  140.  
  141.  
  142.  
  143. TYPE
  144.     CFragUsage1UnionPtr = ^CFragUsage1Union;
  145.     CFragUsage1Union = RECORD
  146.         CASE INTEGER OF
  147.                                                                         {  ! Meaning differs depending on value of "usage". }
  148.         0: (
  149.             appStackSize:        UInt32;                                    {  If the fragment is an application. (Not used by CFM!) }
  150.             );
  151.     END;
  152.  
  153.     CFragUsage2UnionPtr = ^CFragUsage2Union;
  154.     CFragUsage2Union = RECORD
  155.         CASE INTEGER OF
  156.                                                                         {  ! Meaning differs depending on value of "usage". }
  157.         0: (
  158.             appSubdirID:        SInt16;                                    {  If the fragment is an application. }
  159.             );
  160.         1: (
  161.             libFlags:            UInt16;                                    {  If the fragment is an import library. }
  162.             );
  163.     END;
  164.  
  165.  
  166. CONST
  167.                                                                 {  Bit masks for the CFragUsage2Union libFlags variant. }
  168.     kCFragLibUsageMapPrivatelyMask = $0001;                        {  Put container in app heap if necessary. }
  169.  
  170.  
  171. TYPE
  172.     CFragWhere1UnionPtr = ^CFragWhere1Union;
  173.     CFragWhere1Union = RECORD
  174.         CASE INTEGER OF
  175.                                                                         {  ! Meaning differs depending on value of "where". }
  176.         0: (
  177.             spaceID:            UInt32;                                    {  If the fragment is in memory.  (Actually an AddressSpaceID.) }
  178.             );
  179.         1: (
  180.             forkKind:            OSType;                                    {  If the fragment is in an arbitrary byte stream fork. }
  181.             );
  182.     END;
  183.  
  184.     CFragWhere2UnionPtr = ^CFragWhere2Union;
  185.     CFragWhere2Union = RECORD
  186.         CASE INTEGER OF
  187.                                                                         {  ! Meaning differs depending on value of "where". }
  188.         0: (
  189.             forkInstance:        UInt16;                                    {  If the fragment is in an arbitrary byte stream fork. }
  190.             );
  191.     END;
  192.  
  193.  
  194. CONST
  195.     kDefaultCFragNameLen        = 16;
  196.  
  197.  
  198.  
  199. TYPE
  200.     CFragResourceMemberPtr = ^CFragResourceMember;
  201.     CFragResourceMember = RECORD
  202.         architecture:            CFragArchitecture;
  203.         reservedA:                UInt16;                                    {  ! Must be zero! }
  204.         reservedB:                SInt8;                                    {  ! Must be zero! }
  205.         updateLevel:            SInt8;
  206.         currentVersion:            CFragVersionNumber;
  207.         oldDefVersion:            CFragVersionNumber;
  208.         uUsage1:                CFragUsage1Union;
  209.         uUsage2:                CFragUsage2Union;
  210.         usage:                    SInt8;
  211.         where:                    SInt8;
  212.         offset:                    UInt32;
  213.         length:                    UInt32;
  214.         uWhere1:                CFragWhere1Union;
  215.         uWhere2:                CFragWhere2Union;
  216.         extensionCount:            UInt16;                                    {  The number of extensions beyond the name. }
  217.         memberSize:                UInt16;                                    {  Size in bytes, includes all extensions. }
  218.         name:                    PACKED ARRAY [0..15] OF UInt8;            {  ! Actually a sized PString. }
  219.     END;
  220.  
  221.     CFragResourceExtensionHeaderPtr = ^CFragResourceExtensionHeader;
  222.     CFragResourceExtensionHeader = RECORD
  223.         extensionKind:            UInt16;
  224.         extensionSize:            UInt16;
  225.     END;
  226.  
  227.     CFragResourceSearchExtensionPtr = ^CFragResourceSearchExtension;
  228.     CFragResourceSearchExtension = RECORD
  229.         header:                    CFragResourceExtensionHeader;
  230.         libKind:                OSType;
  231.         qualifiers:                SInt8;                                    {  ! Actually four PStrings. }
  232.     END;
  233.  
  234.  
  235. CONST
  236.     kCFragResourceSearchExtensionKind = $30EE;
  237.  
  238.  
  239.  
  240. TYPE
  241.     CFragResourcePtr = ^CFragResource;
  242.     CFragResource = RECORD
  243.         reservedA:                UInt32;                                    {  ! Must be zero! }
  244.         reservedB:                UInt32;                                    {  ! Must be zero! }
  245.         reservedC:                UInt16;                                    {  ! Must be zero! }
  246.         version:                UInt16;
  247.         reservedD:                UInt32;                                    {  ! Must be zero! }
  248.         reservedE:                UInt32;                                    {  ! Must be zero! }
  249.         reservedF:                UInt32;                                    {  ! Must be zero! }
  250.         reservedG:                UInt32;                                    {  ! Must be zero! }
  251.         reservedH:                UInt16;                                    {  ! Must be zero! }
  252.         memberCount:            UInt16;
  253.         firstMember:            CFragResourceMember;
  254.     END;
  255.  
  256.     CFragResourceHandle                    = ^CFragResourcePtr;
  257.  
  258. CONST
  259.     kCurrCFragResourceVersion    = 1;
  260.  
  261.  
  262.  
  263.  
  264. TYPE
  265.     CFragConnectionID = ^LONGINT;
  266.     CFragClosureID = ^LONGINT;
  267.     CFragContainerID = ^LONGINT;
  268.     CFragContextID = ^LONGINT;
  269.     CFragLoadOptions                    = UInt32;
  270.  
  271. CONST
  272.     kReferenceCFrag                = $0001;                        {  Try to use existing copy, increment reference counts. }
  273.     kFindCFrag                    = $0002;                        {  Try find an existing copy, do not increment reference counts. }
  274.     kPrivateCFragCopy            = $0005;                        {  Prepare a new private copy.  (kReferenceCFrag | 0x0004) }
  275.  
  276.  
  277.     kUnresolvedCFragSymbolAddress = 0;
  278.  
  279.  
  280.  
  281. TYPE
  282.     CFragSymbolClass                    = UInt8;
  283.  
  284. CONST
  285.     kCodeCFragSymbol            = 0;
  286.     kDataCFragSymbol            = 1;
  287.     kTVectorCFragSymbol            = 2;
  288.     kTOCCFragSymbol                = 3;
  289.     kGlueCFragSymbol            = 4;
  290.  
  291.  
  292. {
  293.    §
  294.    ===========================================================================================
  295.    Macros and Functions
  296.    ====================
  297. }
  298.  
  299.  
  300.  
  301. FUNCTION GetSharedLibrary(libName: Str63; archType: CFragArchitecture; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  302.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  303.     INLINE $3F3C, $0001, $AA5A;
  304.     {$ENDC}
  305. FUNCTION GetDiskFragment({CONST}VAR fileSpec: FSSpec; offset: UInt32; length: UInt32; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  306.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  307.     INLINE $3F3C, $0002, $AA5A;
  308.     {$ENDC}
  309. FUNCTION GetMemFragment(memAddr: UNIV Ptr; length: UInt32; fragName: Str63; loadFlags: CFragLoadOptions; VAR connID: CFragConnectionID; VAR mainAddr: Ptr; VAR errMessage: Str255): OSErr;
  310.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  311.     INLINE $3F3C, $0003, $AA5A;
  312.     {$ENDC}
  313. FUNCTION CloseConnection(VAR connID: CFragConnectionID): OSErr;
  314.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  315.     INLINE $3F3C, $0004, $AA5A;
  316.     {$ENDC}
  317. FUNCTION FindSymbol(connID: CFragConnectionID; symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr;
  318.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  319.     INLINE $3F3C, $0005, $AA5A;
  320.     {$ENDC}
  321. FUNCTION CountSymbols(connID: CFragConnectionID; VAR symCount: LONGINT): OSErr;
  322.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  323.     INLINE $3F3C, $0006, $AA5A;
  324.     {$ENDC}
  325. FUNCTION GetIndSymbol(connID: CFragConnectionID; symIndex: LONGINT; VAR symName: Str255; VAR symAddr: Ptr; VAR symClass: CFragSymbolClass): OSErr;
  326.     {$IFC TARGET_OS_MAC AND TARGET_CPU_68K AND NOT TARGET_RT_MAC_CFM}
  327.     INLINE $3F3C, $0007, $AA5A;
  328.     {$ENDC}
  329.  
  330. {
  331.    §
  332.    ===========================================================================================
  333.    Initialization & Termination Routines
  334.    =====================================
  335. }
  336.  
  337.  
  338. {
  339.    -----------------------------------------------------------------------------------------
  340.    A fragment's initialization and termination routines are called when a new incarnation of
  341.    the fragment is created or destroyed, respectively.  Exactly when this occurs depends on
  342.    what kinds of section sharing the fragment has and how the fragment is prepared.  Import
  343.    libraries have at most one incarnation per process.  Fragments prepared with option
  344.    kPrivateCFragCopy may have many incarnations per process.
  345.    The initialization function is passed a pointer to an initialization information structure
  346.    and returns an OSErr.  If an initialization function returns a non-zero value the entire
  347.    closure of which it is a part fails.  The C prototype for an initialization function is:
  348.           OSErr    CFragInitFunction    ( const CFragInitBlock *    initBlock );
  349.    The termination procedure takes no parameters and returns nothing.  The C prototype for a
  350.    termination procedure is:
  351.           void    CFragTermProcedure    ( void );
  352.    Note that since the initialization and termination routines are themselves "CFM"-style
  353.    routines whether or not they have the "pascal" keyword is irrelevant.
  354. }
  355.  
  356.  
  357. {
  358.    -----------------------------------------------------------------------------------------
  359.    ! Note:
  360.    ! The "System7" portion of these type names was introduced during the evolution towards
  361.    ! the now defunct Copland version of Mac OS.  Copland was to be called System 8 and there
  362.    ! were slightly different types for System 7 and System 8.  The "generic" type names were
  363.    ! conditionally defined for the desired target system.
  364.    ! Always use the generic types, e.g. CFragInitBlock!  The "System7" names have been kept
  365.    ! only to avoid perturbing code that (improperly) used the target specific type.
  366. }
  367.  
  368.  
  369.  
  370. TYPE
  371.     CFragSystem7MemoryLocatorPtr = ^CFragSystem7MemoryLocator;
  372.     CFragSystem7MemoryLocator = RECORD
  373.         address:                LogicalAddress;
  374.         length:                    UInt32;
  375.         inPlace:                BOOLEAN;
  376.         reservedA:                SInt8;                                    {  ! Must be zero! }
  377.         reservedB:                UInt16;                                    {  ! Must be zero! }
  378.     END;
  379.  
  380.     CFragSystem7DiskFlatLocatorPtr = ^CFragSystem7DiskFlatLocator;
  381.     CFragSystem7DiskFlatLocator = RECORD
  382.         fileSpec:                FSSpecPtr;
  383.         offset:                    UInt32;
  384.         length:                    UInt32;
  385.     END;
  386.  
  387. {  ! This must have a file specification at the same offset as a disk flat locator! }
  388.     CFragSystem7SegmentedLocatorPtr = ^CFragSystem7SegmentedLocator;
  389.     CFragSystem7SegmentedLocator = RECORD
  390.         fileSpec:                FSSpecPtr;
  391.         rsrcType:                OSType;
  392.         rsrcID:                    SInt16;
  393.         reservedA:                UInt16;                                    {  ! Must be zero! }
  394.     END;
  395.  
  396.     CFragSystem7LocatorPtr = ^CFragSystem7Locator;
  397.     CFragSystem7Locator = RECORD
  398.         where:                    SInt32;
  399.         CASE INTEGER OF
  400.         0: (
  401.             onDisk:                CFragSystem7DiskFlatLocator;
  402.             );
  403.         1: (
  404.             inMem:                CFragSystem7MemoryLocator;
  405.             );
  406.         2: (
  407.             inSegs:                CFragSystem7SegmentedLocator;
  408.             );
  409.     END;
  410.  
  411.     CFragSystem7InitBlockPtr = ^CFragSystem7InitBlock;
  412.     CFragSystem7InitBlock = RECORD
  413.         contextID:                CFragContextID;
  414.         closureID:                CFragClosureID;
  415.         connectionID:            CFragConnectionID;
  416.         fragLocator:            CFragSystem7Locator;
  417.         libName:                StringPtr;
  418.         reservedA:                UInt32;                                    {  ! Must be zero! }
  419.     END;
  420.  
  421.     CFragInitBlock                        = CFragSystem7InitBlock;
  422.     CFragInitBlockPtr                     = ^CFragInitBlock;
  423. {  These init/term routine types are only of value to CFM itself. }
  424. {$IFC TYPED_FUNCTION_POINTERS}
  425.     CFragInitFunction = FUNCTION({CONST}VAR initBlock: CFragInitBlock): OSErr; C;
  426. {$ELSEC}
  427.     CFragInitFunction = ProcPtr;
  428. {$ENDC}
  429.  
  430. {$IFC TYPED_FUNCTION_POINTERS}
  431.     CFragTermProcedure = PROCEDURE; C;
  432. {$ELSEC}
  433.     CFragTermProcedure = ProcPtr;
  434. {$ENDC}
  435.  
  436. {
  437.    §
  438.    ===========================================================================================
  439.    Old Name Spellings
  440.    ==================
  441. }
  442.  
  443.  
  444. {
  445.    -------------------------------------------------------------------------------------------
  446.    We've tried to reduce the risk of name collisions in the future by introducing the phrase
  447.    "CFrag" into constant and type names.  The old names are defined below in terms of the new.
  448. }
  449.  
  450.  
  451.  
  452. CONST
  453.     kLoadCFrag                    = $0001;
  454.  
  455.  
  456. {$IFC OLDROUTINENAMES }
  457.  
  458. TYPE
  459.     ConnectionID                        = CFragConnectionID;
  460.     LoadFlags                            = CFragLoadOptions;
  461.     SymClass                            = CFragSymbolClass;
  462.     InitBlock                            = CFragInitBlock;
  463.     InitBlockPtr                         = ^InitBlock;
  464.     MemFragment                            = CFragSystem7MemoryLocator;
  465.     MemFragmentPtr                         = ^MemFragment;
  466.     DiskFragment                        = CFragSystem7DiskFlatLocator;
  467.     DiskFragmentPtr                     = ^DiskFragment;
  468.     SegmentedFragment                    = CFragSystem7SegmentedLocator;
  469.     SegmentedFragmentPtr                 = ^SegmentedFragment;
  470.     FragmentLocator                        = CFragSystem7Locator;
  471.     FragmentLocatorPtr                     = ^FragmentLocator;
  472.     CFragHFSMemoryLocator                = CFragSystem7MemoryLocator;
  473.     CFragHFSMemoryLocatorPtr             = ^CFragHFSMemoryLocator;
  474.     CFragHFSDiskFlatLocator                = CFragSystem7DiskFlatLocator;
  475.     CFragHFSDiskFlatLocatorPtr             = ^CFragHFSDiskFlatLocator;
  476.     CFragHFSSegmentedLocator            = CFragSystem7SegmentedLocator;
  477.     CFragHFSSegmentedLocatorPtr         = ^CFragHFSSegmentedLocator;
  478.     CFragHFSLocator                        = CFragSystem7Locator;
  479.     CFragHFSLocatorPtr                     = ^CFragHFSLocator;
  480.  
  481. CONST
  482.     kPowerPCArch                = 'pwpc';
  483.     kMotorola68KArch            = 'm68k';
  484.     kAnyArchType                = $3F3F3F3F;
  485.     kNoLibName                    = 0;
  486.     kNoConnectionID                = 0;
  487.     kLoadLib                    = $0001;
  488.     kFindLib                    = $0002;
  489.     kNewCFragCopy                = $0005;
  490.     kLoadNewCopy                = $0005;
  491.     kUseInPlace                    = $80;
  492.     kCodeSym                    = 0;
  493.     kDataSym                    = 1;
  494.     kTVectSym                    = 2;
  495.     kTOCSym                        = 3;
  496.     kGlueSym                    = 4;
  497.     kInMem                        = 0;
  498.     kOnDiskFlat                    = 1;
  499.     kOnDiskSegmented            = 2;
  500.     kIsLib                        = 0;
  501.     kIsApp                        = 1;
  502.     kIsDropIn                    = 2;
  503.     kFullLib                    = 0;
  504.     kUpdateLib                    = 1;
  505.     kWholeFork                    = 0;
  506.     kCFMRsrcType                = 'cfrg';
  507.     kCFMRsrcID                    = 0;
  508.     kSHLBFileType                = 'shlb';
  509.     kUnresolvedSymbolAddress    = 0;
  510.  
  511.     kPowerPC                    = 'pwpc';
  512.     kMotorola68K                = 'm68k';
  513.  
  514. {$ENDC}  {OLDROUTINENAMES}
  515.  
  516.  
  517.  
  518.  
  519.  
  520. {$ALIGN RESET}
  521. {$POP}
  522.  
  523. {$SETC UsingIncludes := CodeFragmentsIncludes}
  524.  
  525. {$ENDC} {__CODEFRAGMENTS__}
  526.  
  527. {$IFC NOT UsingIncludes}
  528.  END.
  529. {$ENDC}
  530.